/* vim: set ts=2 et sw=2 cindent fo=qroca: */

package com.globant.google.mendoza.malbec.transport;

/** Abstracts the underlying transport.
 *
 * This interface specifies a transport mechanism to allow the merchant and
 * GBuy the exchange of messages. Implementation of this interface integrates
 * with different integration needs, such a stand alone application or a
 * servlet based container.
 */
public interface Transport {

  /** Sends a message to the server.
   *
   * @param message The message to send to the server. It cannot be null.
   *
   * @return Returns the server response, usually an acknowledge or an error
   * related to the validity of the message structure.
   */
  String send(final String message);

  /** Registers a receiver for this transport.
   *
   * When GBuy sends a message to a merchant, this transport notifies the
   * client using the receiver.
   *
   * @param receiver The receiver that is notified of the message
   * availability.
   */
  void registerReceiver(final Receiver receiver);

  /** Starts listening to requests.
   *
   * You must have registered a receiver before calling start. The registered
   * receiver is notified of new requests.
   */
  void start();

  /** Stops the server.
   *
   * Depending on the implementation, this function will stop listening to
   * requests or will simply ignore all requests. After stop is called, no more
   * events are received through the registered receiver.
   */
  void stop();
  
  /** Sets the url to use to send messages to GBuy.
   *
   * @param url The url. Cannot be null.
   */
  void setServerURL(final String url);
}

